<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>numpy.ufunc.reduce &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <script type="text/javascript" src="../../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../../about.html" >
    <link rel="index" title="Index" href="../../genindex.html" >
    <link rel="search" title="Search" href="../../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../../index.html" >
    <link rel="up" title="Universal functions (ufunc)" href="../ufuncs.html" >
    <link rel="next" title="numpy.ufunc.accumulate" href="numpy.ufunc.accumulate.html" >
    <link rel="prev" title="numpy.ufunc.signature" href="numpy.ufunc.signature.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../../index.html">
      <img border=0 alt="NumPy" src="../../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="../index.html" >NumPy Reference</a></li>
          <li class="active"><a href="../ufuncs.html" accesskey="U">Universal functions (<code class="xref py py-class docutils literal notranslate"><span class="pre">ufunc</span></code>)</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="numpy.ufunc.accumulate.html" title="numpy.ufunc.accumulate"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="numpy.ufunc.signature.html" title="numpy.ufunc.signature"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h4>Previous topic</h4>
  <p class="topless"><a href="numpy.ufunc.signature.html"
                        title="previous chapter">numpy.ufunc.signature</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="numpy.ufunc.accumulate.html"
                        title="next chapter">numpy.ufunc.accumulate</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="numpy-ufunc-reduce">
<h1>numpy.ufunc.reduce<a class="headerlink" href="#numpy-ufunc-reduce" title="Permalink to this headline">¶</a></h1>
<p>method</p>
<dl class="method">
<dt id="numpy.ufunc.reduce">
<code class="sig-prename descclassname">ufunc.</code><code class="sig-name descname">reduce</code><span class="sig-paren">(</span><em class="sig-param">a</em>, <em class="sig-param">axis=0</em>, <em class="sig-param">dtype=None</em>, <em class="sig-param">out=None</em>, <em class="sig-param">keepdims=False</em>, <em class="sig-param">initial=&lt;no value&gt;</em>, <em class="sig-param">where=True</em><span class="sig-paren">)</span><a class="headerlink" href="#numpy.ufunc.reduce" title="Permalink to this definition">¶</a></dt>
<dd><p>Reduces <em class="xref py py-obj">a</em>’s dimension by one, by applying ufunc along one axis.</p>
<p>Let <img class="math" src="../../_images/math/51a544716c84273279aa637de7046df43bc12fea.svg" alt="a.shape = (N_0, ..., N_i, ..., N_{M-1})"/>.  Then
<img class="math" src="../../_images/math/2a2b95efb89ae2854f0ad3bf9adc2562e519110f.svg" alt="ufunc.reduce(a, axis=i)[k_0, ..,k_{i-1}, k_{i+1}, .., k_{M-1}]"/> =
the result of iterating <em class="xref py py-obj">j</em> over <img class="math" src="../../_images/math/1aad82c8568a0b3f7bfaa3172c48fc3f881972ef.svg" alt="range(N_i)"/>, cumulatively applying
ufunc to each <img class="math" src="../../_images/math/b4bbb3381430b91f18a5c8027eaeb8caf394de4e.svg" alt="a[k_0, ..,k_{i-1}, j, k_{i+1}, .., k_{M-1}]"/>.
For a one-dimensional array, reduce produces results equivalent to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">r</span> <span class="o">=</span> <span class="n">op</span><span class="o">.</span><span class="n">identity</span> <span class="c1"># op = ufunc</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">A</span><span class="p">)):</span>
  <span class="n">r</span> <span class="o">=</span> <span class="n">op</span><span class="p">(</span><span class="n">r</span><span class="p">,</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>
<span class="k">return</span> <span class="n">r</span>
</pre></div>
</div>
<p>For example, add.reduce() is equivalent to sum().</p>
<dl class="field-list">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl>
<dt><strong>a</strong><span class="classifier">array_like</span></dt><dd><p>The array to act on.</p>
</dd>
<dt><strong>axis</strong><span class="classifier">None or int or tuple of ints, optional</span></dt><dd><p>Axis or axes along which a reduction is performed.
The default (<em class="xref py py-obj">axis</em> = 0) is perform a reduction over the first
dimension of the input array. <em class="xref py py-obj">axis</em> may be negative, in
which case it counts from the last to the first axis.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.7.0.</span></p>
</div>
<p>If this is None, a reduction is performed over all the axes.
If this is a tuple of ints, a reduction is performed on multiple
axes, instead of a single axis or all the axes as before.</p>
<p>For operations which are either not commutative or not associative,
doing a reduction over multiple axes is not well-defined. The
ufuncs do not currently raise an exception in this case, but will
likely do so in the future.</p>
</dd>
<dt><strong>dtype</strong><span class="classifier">data-type code, optional</span></dt><dd><p>The type used to represent the intermediate results. Defaults
to the data-type of the output array if this is provided, or
the data-type of the input array if no output array is provided.</p>
</dd>
<dt><strong>out</strong><span class="classifier">ndarray, None, or tuple of ndarray and None, optional</span></dt><dd><p>A location into which the result is stored. If not provided or None,
a freshly-allocated array is returned. For consistency with
<code class="docutils literal notranslate"><span class="pre">ufunc.__call__</span></code>, if given as a keyword, this may be wrapped in a
1-element tuple.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.13.0: </span>Tuples are allowed for keyword argument.</p>
</div>
</dd>
<dt><strong>keepdims</strong><span class="classifier">bool, optional</span></dt><dd><p>If this is set to True, the axes which are reduced are left
in the result as dimensions with size one. With this option,
the result will broadcast correctly against the original <em class="xref py py-obj">arr</em>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.7.0.</span></p>
</div>
</dd>
<dt><strong>initial</strong><span class="classifier">scalar, optional</span></dt><dd><p>The value with which to start the reduction.
If the ufunc has no identity or the dtype is object, this defaults
to None - otherwise it defaults to ufunc.identity.
If <code class="docutils literal notranslate"><span class="pre">None</span></code> is given, the first element of the reduction is used,
and an error is thrown if the reduction is empty.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.15.0.</span></p>
</div>
</dd>
<dt><strong>where</strong><span class="classifier">array_like of bool, optional</span></dt><dd><p>A boolean array which is broadcasted to match the dimensions
of <em class="xref py py-obj">a</em>, and selects elements to include in the reduction. Note
that for ufuncs like <code class="docutils literal notranslate"><span class="pre">minimum</span></code> that do not have an identity
defined, one has to pass in also <code class="docutils literal notranslate"><span class="pre">initial</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.17.0.</span></p>
</div>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl class="simple">
<dt><strong>r</strong><span class="classifier">ndarray</span></dt><dd><p>The reduced array. If <em class="xref py py-obj">out</em> was supplied, <em class="xref py py-obj">r</em> is a reference to it.</p>
</dd>
</dl>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">multiply</span><span class="o">.</span><span class="n">reduce</span><span class="p">([</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">5</span><span class="p">])</span>
<span class="go">30</span>
</pre></div>
</div>
<p>A multi-dimensional array example:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">X</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">8</span><span class="p">)</span><span class="o">.</span><span class="n">reshape</span><span class="p">((</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">X</span>
<span class="go">array([[[0, 1],</span>
<span class="go">        [2, 3]],</span>
<span class="go">       [[4, 5],</span>
<span class="go">        [6, 7]]])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">add</span><span class="o">.</span><span class="n">reduce</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="go">array([[ 4,  6],</span>
<span class="go">       [ 8, 10]])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">add</span><span class="o">.</span><span class="n">reduce</span><span class="p">(</span><span class="n">X</span><span class="p">)</span> <span class="c1"># confirm: default axis value is 0</span>
<span class="go">array([[ 4,  6],</span>
<span class="go">       [ 8, 10]])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">add</span><span class="o">.</span><span class="n">reduce</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="go">array([[ 2,  4],</span>
<span class="go">       [10, 12]])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">add</span><span class="o">.</span><span class="n">reduce</span><span class="p">(</span><span class="n">X</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="go">array([[ 1,  5],</span>
<span class="go">       [ 9, 13]])</span>
</pre></div>
</div>
<p>You can use the <code class="docutils literal notranslate"><span class="pre">initial</span></code> keyword argument to initialize the reduction
with a different value, and <code class="docutils literal notranslate"><span class="pre">where</span></code> to select specific elements to include:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">add</span><span class="o">.</span><span class="n">reduce</span><span class="p">([</span><span class="mi">10</span><span class="p">],</span> <span class="n">initial</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
<span class="go">15</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">add</span><span class="o">.</span><span class="n">reduce</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">ones</span><span class="p">((</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">)),</span> <span class="n">axis</span><span class="o">=</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="n">initial</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span>
<span class="go">array([14., 14.])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">10.</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">nan</span><span class="p">,</span> <span class="mi">10</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">add</span><span class="o">.</span><span class="n">reduce</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">where</span><span class="o">=~</span><span class="n">np</span><span class="o">.</span><span class="n">isnan</span><span class="p">(</span><span class="n">a</span><span class="p">))</span>
<span class="go">20.0</span>
</pre></div>
</div>
<p>Allows reductions of empty arrays where they would normally fail, i.e.
for ufuncs without an identity.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">minimum</span><span class="o">.</span><span class="n">reduce</span><span class="p">([],</span> <span class="n">initial</span><span class="o">=</span><span class="n">np</span><span class="o">.</span><span class="n">inf</span><span class="p">)</span>
<span class="go">inf</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">minimum</span><span class="o">.</span><span class="n">reduce</span><span class="p">([[</span><span class="mf">1.</span><span class="p">,</span> <span class="mf">2.</span><span class="p">],</span> <span class="p">[</span><span class="mf">3.</span><span class="p">,</span> <span class="mf">4.</span><span class="p">]],</span> <span class="n">initial</span><span class="o">=</span><span class="mf">10.</span><span class="p">,</span> <span class="n">where</span><span class="o">=</span><span class="p">[</span><span class="kc">True</span><span class="p">,</span> <span class="kc">False</span><span class="p">])</span>
<span class="go">array([ 1., 10.])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">minimum</span><span class="o">.</span><span class="n">reduce</span><span class="p">([])</span>
<span class="gt">Traceback (most recent call last):</span>
    <span class="o">...</span>
<span class="gr">ValueError</span>: <span class="n">zero-size array to reduction operation minimum which has no identity</span>
</pre></div>
</div>
</dd></dl>

</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>